home *** CD-ROM | disk | FTP | other *** search
PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) NNNNAAAAMMMMEEEE PDReadStatus, PDReadOpStatus, PDLocalReadStatus, PDLocalReadOpStatus, PDLocalWriteStatus - reads/writes the printer status SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ppppoooodddd....hhhh>>>> iiiinnnntttt PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____nnnnaaaammmmeeee,,,, PPPPDDDDSSSSttttaaaattttuuuussssSSSSttttrrrruuuucccctttt ********ssssttttaaaattttuuuusssspppp,,,, PPPPDDDDMMMMeeeessssssssaaaaggggeeeeSSSSttttrrrruuuucccctttt ********mmmmeeeessssssssaaaaggggeeeesssspppp,,,, ttttiiiimmmmeeee____tttt ****mmmmoooodddd____ttttiiiimmmmeeeepppp))));;;; iiiinnnntttt PPPPDDDDLLLLooooccccaaaallllRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____nnnnaaaammmmeeee,,,, PPPPDDDDSSSSttttaaaattttuuuussssSSSSttttrrrruuuucccctttt ********ssssttttaaaattttuuuusssspppp,,,, PPPPDDDDMMMMeeeessssssssaaaaggggeeeeSSSSttttrrrruuuucccctttt ********mmmmeeeessssssssaaaaggggeeeesssspppp,,,, ttttiiiimmmmeeee____tttt ****mmmmoooodddd____ttttiiiimmmmeeeepppp))));;;; iiiinnnntttt PPPPDDDDRRRReeeeaaaaddddOOOOppppSSSSttttaaaattttuuuussss((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____nnnnaaaammmmeeee,,,, iiiinnnntttt ****oooopppp____ssssttttaaaattttuuuusssspppp,,,, ttttiiiimmmmeeee____tttt ****mmmmoooodddd____ttttiiiimmmmeeeepppp))));;;; iiiinnnntttt PPPPDDDDLLLLooooccccaaaallllRRRReeeeaaaaddddOOOOppppSSSSttttaaaattttuuuussss((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____nnnnaaaammmmeeee,,,, iiiinnnntttt ****oooopppp____ssssttttaaaattttuuuusssspppp,,,, ttttiiiimmmmeeee____tttt ****mmmmoooodddd____ttttiiiimmmmeeeepppp))));;;; iiiinnnntttt PPPPDDDDLLLLooooccccaaaallllWWWWrrrriiiitttteeeeSSSSttttaaaattttuuuussss((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____nnnnaaaammmmeeee,,,, PPPPDDDDSSSSttttaaaattttuuuussssSSSSttttrrrruuuucccctttt ****ssssttttaaaattttuuuussss,,,, PPPPDDDDMMMMeeeessssssssaaaaggggeeeeSSSSttttrrrruuuucccctttt ****mmmmeeeessssssssaaaaggggeeeessss))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _P_D_R_e_a_d_S_t_a_t_u_s and _P_D_L_o_c_a_l_R_e_a_d_S_t_a_t_u_s provide detailed information on the operational status of the specified printer, _p_r_i_n_t_e_r__n_a_m_e. The functions fill and return a _P_D_S_t_a_t_u_s_S_t_r_u_c_t with status information and return an array of _P_D_M_e_s_s_a_g_e_S_t_r_u_c_t messages. The message list consists of errors, warnings and general information related to the current operational condition of the printer. The number of messages in the list is given by the _e_r_r_o_r__c_o_u_n_t field of the _P_D_S_t_a_t_u_s_S_t_r_u_c_t. There will be a maximum of PPPPDDDD____MMMMEEEESSSSSSSSAAAAGGGGEEEE____MMMMAAAAXXXX messages in the list. If _e_r_r_o_r__c_o_u_n_t is 0, the value of _m_e_s_s_a_g_e_s_p is undefined. _P_D_R_e_a_d_O_p_S_t_a_t_u_s and _P_D_L_o_c_a_l_R_e_a_d_O_p_S_t_a_t_u_s also provide printer status information. However, only the _o_p_e_r_a_t_i_o_n_a_l__s_t_a_t_u_s field of the _P_D_S_t_a_t_u_s_S_t_r_u_c_t is returned. The status reading functions all set _m_o_d__t_i_m_e_p to the time the printer status information was last modified (see _t_i_m_e(_2)). _P_D_L_o_c_a_l_W_r_i_t_e_S_t_a_t_u_s writes the specified _P_D_S_t_a_t_u_s_S_t_r_u_c_t and _P_D_M_e_s_s_a_g_e_S_t_r_u_c_t information to the specified printer's status file. _m_e_s_s_a_g_e_s is expected to be an array of message structures. The number of messages in the array must be the same as the number in the _e_r_r_o_r__c_o_u_n_t field of the _P_D_S_t_a_t_u_s_S_t_r_u_c_t and must not exceed PPPPDDDD____MMMMEEEESSSSSSSSAAAAGGGGEEEE____MMMMAAAAXXXX. If there PPPPaaaaggggeeee 1111 PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) are no messages to write, _m_e_s_s_a_g_e_s may be specified as NNNNUUUULLLLLLLL. _l_i_b_p_o_d provides the _P_D_M_a_k_e_M_e_s_s_a_g_e convenience function to assist in filling a _P_D_M_e_s_s_a_g_e_S_t_r_u_c_t. Refer to the _l_i_b_p_o_d(_3) man page for information about the "Local" functions. The _P_D_S_t_a_t_u_s_S_t_r_u_c_t structure is defined as follows. typedef struct _pdStatusStruct { int operational_status; /* Printer status */ int error_count; /* Number of messages */ /* error, warning & info */ int media_type; /* Media type */ int number_of_colors; /* Number of colors */ int media_size; /* Media size */ char printer_options[PD_STR_MAX]; /* Option info */ /* (e.g. "8 MB RAM") */ char validation_mask; /* Size validation mask */ } PDStatusStruct; _o_p_e_r_a_t_i_o_n_a_l__s_t_a_t_u_s Code indicating the operational status of the printer (see _p_o_d._h). _e_r_r_o_r__c_o_u_n_t Total number of error, warning and information messages available in the _e_r_r__s_t_a_t_u_s field of the _P_D_I_n_f_o_S_t_r_u_c_t and in the _m_e_s_s_a_g_e_s_p array returned by _P_D_R_e_a_d_S_t_a_t_u_s and _P_D_L_o_c_a_l_R_e_a_d_S_t_a_t_u_s. When calling _P_D_L_o_c_a_l_W_r_i_t_e_S_t_a_t_u_s the number of message specified by this field must match the number of messages in the _m_e_s_s_a_g_e_s_p array and must not exceed PPPPDDDD____MMMMEEEESSSSSSSSAAAAGGGGEEEE____MMMMAAAAXXXX. _m_e_d_i_a__t_y_p_e Code indicating the media type installed in the printer (see _p_o_d._h). _n_u_m_b_e_r__o_f__c_o_l_o_r_s This field is a bitmask in which the number of colors, colorspace, pixel depth and data format are specified. The value for this field is constructed by bitwise OR'ing the values for each of these attributes. The bitmasks used in this field are all prefixed PPPPDDDD____DDDDAAAATTTTAAAA____ and can be found in _p_o_d._h. Refer to this file for a list of all possible bitmasks. For example, to specify an RGB colorspace with eight bits per pixel and a planar data format set this field to PPPPDDDD____DDDDAAAATTTTAAAA____PPPPLLLLAAAANNNNAAAARRRR |||| PPPPDDDD____DDDDAAAATTTTAAAA____DDDDEEEEPPPPTTTTHHHH8888 |||| PPPPDDDD____DDDDAAAATTTTAAAA____RRRRGGGGBBBB. The default values for these fields are PPPPDDDD____DDDDAAAATTTTAAAA____KKKK, PPPPDDDD____DDDDAAAATTTTAAAA____DDDDEEEEPPPPTTTTHHHH1111 and PPPPDDDD____DDDDAAAATTTTAAAA____CCCCHHHHUUUUNNNNKKKKYYYY. Macros are provided to decompose this field into its component codes. For example, to determine the data depth the macro PPPPDDDD____GGGGEEEETTTT____DDDDEEEEPPPPTTTTHHHH____CCCCOOOODDDDEEEE((((nnnnuuuummmmbbbbeeeerrrr____ooooffff____ccccoooolllloooorrrrssss)))) would be used. Refer to _p_o_d._h for a list of these macros. PPPPaaaaggggeeee 2222 PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) _m_e_d_i_a__s_i_z_e Media size code (see _p_o_d._h). _p_r_i_n_t_e_r__o_p_t_i_o_n_s Installed printer options (e.g. "8 MByte RAM"). This string is also used to indicate the current printer resolution for printers that support multiple output resolutions. While the _P_D_I_n_f_o_S_t_r_u_c_t contains a resolution field, typically the nominal resolution is stated. To specify the current resolution place "CurrentRes = <xres> x <yres>" in this string. <xres> and <yres> should be replaced with the current output resolution. Note that the 'x' can be specified as 'X' or ',' and whitespace before and after the character is optional. Printer drivers should update this string and filter programs that require the current output resolution should parse for this string before falling back to using the resolutions in the _P_D_I_n_f_o_S_t_r_u_c_t. If a resolution string is not specified in this field, the resolution is assumed to be that specified in the _P_D_I_n_f_o_S_t_r_u_c_t. The convenience function _P_D_G_e_t_C_u_r_r_e_n_t_R_e_s_o_l_u_t_i_o_n(_3) performs the above procedure and returns the current output resolution. _v_a_l_i_d_a_t_i_o_n__m_a_s_k Size table entry validation mask. If _P_D_F_i_n_d_P_a_g_e_S_i_z_e is called with a size code of PPPPDDDD____SSSSIIIIZZZZEEEE____CCCCUUUURRRRRRRREEEENNNNTTTT, dimensional information for the currently loaded paper size will be returned. The mechanics of determining this information is as follows. The _m_e_d_i_a__s_i_z_e field of the _P_D_S_t_a_t_u_s_S_t_r_u_c_t is used as the size code to search the page table in the _P_D_I_n_f_o_S_t_r_u_c_t. This table contains size information for each page size the printer supports. Each page table entry has a validation mask as well as a size code. Dimensional information is returned for the page size entry that matches the _m_e_d_i_a__s_i_z_e value and whose validation masks satisfy the relationship (_s_t_a_t_u_s _m_a_s_k & _t_a_b_l_e _m_a_s_k) == _s_t_a_t_u_s _m_a_s_k. The validation mask can be helpful in specifying page dimensions for printers that support multiple resolutions. The page table can contain a number of page names that are identical but with dimensions appropriate to different resolutions. Each entry would have a unique validation mask. This way the status validation mask could be used to select the proper page size for the current output resolution. The _P_D_M_e_s_s_a_g_e_S_t_r_u_c_t is defined as follows. typedef struct _pdMessageStruct { int message_code; char message_text[PD_STR_MAX]; } PDMessageStruct; PPPPaaaaggggeeee 3333 PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) _m_e_s_s_a_g_e__c_o_d_e Error, warning or information message code ID (see _p_o_d._h). _m_e_s_s_a_g_e__t_e_x_t Text for the message truncated to a length of PD_STR_MAX-1. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE 0 is returned if execution was successful. -1 is returned and _P_D_e_r_r_n_o is set if an execution error has occurred. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS _P_D_L_o_c_a_l_R_e_a_d_S_t_a_t_u_s, _P_D_L_o_c_a_l_R_e_a_d_O_p_S_t_a_t_u_s, _P_D_R_e_a_d_S_t_a_t_u_s and _P_D_R_e_a_d_O_p_S_t_a_t_u_s will fail under the following circumstances. PD_LIBERR_BAD_PNAME A NULL or empty printer name string has been specified. PD_LIBERR_STATUS_READ The status file could not be opened for reading or an error occurred while reading the file. In addition, _P_D_R_e_a_d_S_t_a_t_u_s and _P_D_R_e_a_d_O_p_S_t_a_t_u_s will fail under the following circumstances. PD_LIBERR_NO_PRINTER The specified printer has not been registered with the printer spooling system and is, therefore, inaccessible. PD_LIBERR_BAD_HOSTNAME The network address of the specified hostname could not be found. PD_LIBERR_NETWORK For an unknown reason, a network connection could not be made with the remote printer host. PD_LIBERR_NET_TIMEOUT A timeout occurred while attempting to communicate with the remote printer host. PD_LIBERR_NET_INTR The program has been interrupted while attempting to communicate with the remote printer host. PD_LIBERR_NET_NOTREG The podd daemon is not registered on the remote printer host. PD_LIBERR_NET_PMAP The port mapper daemon failed on the remote printer host. PD_LIBERR_NET_NOPROC The client has called a libpod function that is not supported by the podd daemon on the remote printer host. PPPPaaaaggggeeee 4444 PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) PD_LIBERR_NET_CLNTXDR The libpod library XDR routines and the kernel's XDR routines are incompatible. PD_LIBERR_NET_SVCXDR The podd daemon XDR routines and the remote printer host's kernel XDR routines are incompatible. PD_LIBERR_NET_RPCMATCH The version of RPC software on the client is incompatible with the version on the remote printer host. PD_LIBERR_NET_PROCMATCH The version of the specified libpod function on the client is incompatible with the version on the remote printer host. _P_D_L_o_c_a_l_W_r_i_t_e_S_t_a_t_u_s will fail under the following circumstances. PD_LIBERR_BAD_STRUCT A NULL structure pointer has been specified. PD_LIBERR_BAD_PNAME A NULL or empty printer name string has been specified. PD_LIBERR_STATUS_WRITE The status file could not be opened for writing or an error occurred while writing the file. PD_LIBERR_MAX_MESSAGE A request has been made to write more than PPPPDDDD____MMMMEEEESSSSSSSSAAAAGGGGEEEE____MMMMAAAAXXXX messages to the status file. PD_LIBERR_BAD_MSGCNT An invalid value has been specified for the number of messages to write to the status file. WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS 1. Upon successful execution, the _P_D_R_e_a_d_S_t_a_t_u_s and _P_D_L_o_c_a_l_R_e_a_d_S_t_a_t_u_s functions sets _s_t_a_t_u_s_p and _m_e_s_s_a_g_e_s_p to point to internal copies of the _P_D_S_t_a_t_u_s_S_t_r_u_c_t and _P_D_M_e_s_s_a_g_e_s_S_t_r_u_c_t list respectively. The contents of these structures can change after each _l_i_b_p_o_d function call. To preserve the contents of the structures across subsequent _l_i_b_p_o_d calls, they should be copied into user-allocated storage. 2. The functions _P_D_R_e_a_d_S_t_a_t_u_s and _P_D_R_e_a_d_O_p_S_t_a_t_u_s call the _l_i_b_s_p_o_o_l function _S_L_G_e_t_P_r_i_n_t_e_r_I_n_f_o. This _l_i_b_s_p_o_o_l function is not reentrant. This means that any pointer returned by a previous call to _S_L_G_e_t_P_r_i_n_t_e_r_I_n_f_o will be invalid after a call to either _P_D_R_e_a_d_S_t_a_t_u_s or _P_D_R_e_a_d_O_p_S_t_a_t_u_s. NNNNOOOOTTTTEEEESSSS 1. Since the POD files are owned by the lp account, super-user or lp account privilege is required to successfully call the _P_D_L_o_c_a_l_W_r_i_t_e_S_t_a_t_u_s function. PPPPaaaaggggeeee 5555 PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo PPPPDDDDRRRReeeeaaaaddddSSSSttttaaaattttuuuussss((((3333)))) 2. The _P_D_L_o_c_a_l_W_r_i_t_e_S_t_a_t_u_s function writes to the status file only if the status information and messages in the file differ from those specified as parameters to the function. The modification time of the status file is updated only if a write takes place. FFFFIIIILLLLEEEESSSS /var/spool/lp/pod/[printer name].status SSSSEEEEEEEE AAAALLLLSSSSOOOO PDMakeMessage(3), PDReadInfo(3), libpod(3), time(2), ctime(3) PPPPaaaaggggeeee 6666 
